home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 41
/
Aminet 41 (2001)(Schatztruhe)[!][Feb 2001].iso
/
Aminet
/
util
/
wb
/
VisualPrefs.lha
/
VisualPrefs
/
DocsEnglish
/
VP-Developer.doc
< prev
next >
Wrap
Text File
|
1999-12-13
|
7KB
|
158 lines
Last update: 8.12.99
Introducing
THE VISUALPREFS DEVELOPER INTERFACE
A work in progress
If you're a developer, you can take advantage of some features of VisualPrefs.
Although there's not a full developer API for VisualPrefs yet, it's already
possible to use the BOOPSI classes that VisualPrefs adds to the system.
The purpose of these classes is to give programmers an easy way to get the
"VisualPrefs look", without having to wait for me to implement a patch for
their applications in VisualPrefs. ;-)
Currently there's just one class:
"tbiclass" - the titlebar image class
This class provides the most commonly used images for gadgets added by
applications to the titlebar of their windows. Examples of this are the
ubiquitous "iconify" gadget or DirOpus 5's "padlock" gadget.
All programs using this class will automatically get the same look for their
titlebar images if VisualPrefs is running. This is probably better than
having myriads of different versions of the same image...
You can use "tbiclass" just like "sysiclass"; they're both sub-classes of
"imageclass". A "tbiclass" image can be created by calling NewObject() with
the following tags:
SYSIA_DrawInfo - This is absolutely mandatory. You MUST pass a DrawInfo
pointer to "tbiclass" or NewObject() will fail.
SYSIA_Which - To specify which image you want; currently there are six image
types:
POPUPIMAGE - A MUI "pop-up" titlebar gadget image
MUIIMAGE - A MUI "settings" titlebar gadget image
SNAPSHOTIMAGE - A MUI "snapshot" titlebar gadget image
ICONIFYIMAGE - An "iconify" titlebar gadget image
PADLOCKIMAGE - A DirOpus "padlock" titlebar gadget image
TBFRAMEIMAGE - A general-purpose empty titlebar gadget image
IA_Width, IA_Height - These are only recognized by the TBFRAMEIMAGE type;
the other image types ignore them and always have
the same size of the depth gadget image.
SYSIA_ReferenceFont - This is only recognized by the TBFRAMEIMAGE type;
the other image types ignore it and always have
the same height of the depth gadget image.
TBIA_FullFrame - This is only recognized by the TBFRAMEIMAGE type; set it
to TRUE to get an image which also contains an inner frame,
if the current style has one. This is best suited when the
image contents are graphic in nature. Set it to FALSE to
get an image which has at most the outer frame; this is
instead best suited when the image must contain text (as
the inner frame might be too small to render the text into).
The default is FALSE. (Available since VisualPrefs 41.38)
You can also use this tag with GetAttr():
TBIA_ContentsBox - To ask the image about the position and size of its
actual "contents box" relative to the image itself.
Said box is the part where, if you need to, you can
add any further custom imagery. This probably only
makes sense with TBFRAMEIMAGE images. To position
correctly the box, you should add its Left and Top
offsets to those of the image. Note that, even within
the returned dimensions, you should always leave a
small space (like two pixels) around your imagery,
to achieve better-looking results. This is a read-only
attribute; the value you pass to this tag must be a
pointer to an IBox structure. Do NOT pass a longword
pointer! (Available since VisualPrefs 41.35)
Of course, if NewObject() fails, you should provide a built-in fallback image
for your titlebar gadget. However, I have released a disk-based freeware
"tbiclass" image class (dev/gui/titlebar_ic.lha) which you can include in the
distribution of your applications. This class will provide the needed images
and will be automatically replaced by the VisualPrefs one if it is present.
Therefore, you can keep your built-in images very simple, or not have
them at all ;-)
If you use TBFRAMEIMAGE to make your own special titlebar images, you can
add contents to it in two ways: by setting the NextImage field to the address
of your custom inner imagery, or by sub-classing "tbiclass" and redefining
the IM_DRAW/IM_DRAWFRAME methods (of course, in this case you must let the
superclass do its rendering first!).
It's important to note that all "tbiclass" image instances will have an
Image->LeftEdge value of -1. This shouldn't be modified, and you should
place your titlebar gadgets accordingly. The reason for this apparently
strange behavior is that Intuition titlebar gadget images, too, work this
way, and we should try to stay as compatible with Intuition as possible.
Also, make sure you adjust your gadget's size if necessary, to adapt it
to the returned image's size.
An example of all this could be:
...
/* Create the image */
if (!(iconifyimage = NewObject(NULL,"tbiclass",SYSIA_Which,ICONIFYIMAGE,
SYSIA_DrawInfo,dri,
TAG_END)))
{
iconifyimage = builtin_iconifyimage;
}
/* Use the image */
gad->GadgetRender = iconifyimage;
...
/* Free the image */
if (iconifyimage != builtin_iconifyimage) DisposeObject(iconifyimage);
...
That's all. The real include file for "tbiclass" is in the Aminet stand-alone
release, anyway all you need in order to use "tbiclass" in your applications
is to paste the following few lines at the beginning of your source code. :-]
------- cut here -------8<------- cut here -------8<------- cut here -------
#define POPUPIMAGE (101)
#define MUIIMAGE (102)
#define SNAPSHOTIMAGE (103)
#define ICONIFYIMAGE (104)
#define PADLOCKIMAGE (105)
#define TBFRAMEIMAGE (106)
#define TBIA_Dummy (TAG_USER + 0x0B0000)
#define TBIA_ContentsBox (TBIA_Dummy + 0x0001)
#define TBIA_FullFrame (TBIA_Dummy + 0x0002)
------- cut here -------8<------- cut here -------8<------- cut here -------
There's already an application using "tbiclass", ViNCEd by Thomas Richter.
I hope you will also support "tbiclass" and contribute this way to finally
give a consistent appearance to all titlebar gadgets used in applications!
Thank you,
Massimo Tantignone (tanti@intercom.it)